ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX,,,, ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX,,,, ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX - take
ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX and ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX are
part of the GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss extension.
Instruments allow an application to measure performance of the GL
pipeline and identify possible bottlenecks. This information may be
useful in feedback-based load management schemes which attempt to
maintain a constant frame-rate, or in tuning an application for best
performance.
GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss provides an instrumentation framework, but no
instruments. The set of available instruments varies between OpenGL
implementations, and can be determined by querying the GGGGLLLL____EEEEXXXXTTTTEEEENNNNSSSSIIIIOOOONNNNSSSS
string returned by ggggllllGGGGeeeettttSSSSttttrrrriiiinnnngggg for the names of the extensions that
implement the instruments.
Unlike feedback and selection (see ggggllllSSSSeeeelllleeeeccccttttBBBBuuuuffffffffeeeerrrr and ggggllllFFFFeeeeeeeeddddbbbbaaaacccckkkkBBBBuuuuffffffffeeeerrrr),
GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss provides commands that allow measurements to be
delivered asynchronously, so that the graphics pipeline need not be
stalled while measurements are returned to the client.
A buffer in which to collect instrument measurements is specified with
ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. _s_i_z_e specifies the size of the buffer, as a
count of GLints. The buffer will be prepared in a way that allows it to
be written asynchronously by the graphics pipeline. If the same _b_u_f_f_e_r
was specified on a previous call, the buffer is reset; that is,
measurements taken after the call to ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX will be
written to the start of the buffer. If _b_u_f_f_e_r is zero, then any
resources allocated by a previous call to prepare the buffer for writing
will be freed. If _b_u_f_f_e_r is non-zero, but is different from a previous
call, the old buffer is replaced by the new buffer and any allocated
resources involved in preparing the old buffer for writing are freed.
The buffer address can be queried with ggggllllGGGGeeeettttPPPPooooiiiinnnntttteeeerrrrvvvvEEEEXXXXTTTT using argument
To enable an instrument, use ggggllllEEEEnnnnaaaabbbblllleeee with an argument that specifies the
instrument. The argument to use for a particular instrument is
determined by the OpenGL extension that supports that instrument. (See
below for an example.)
To start the currently-enabled instrument(s) call ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX.
To take a measurement use ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. To stop the currently-
enabled instruments and take a final measurement use
ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. The parameter _m_a_r_k_e_r will be passed through the
pipe and written to the buffer to ease the task of interpreting it.
The format of any instrument measurement in the buffer obeys certain
conventions. The first word of the measurement is the ggggllllEEEEnnnnaaaabbbblllleeee enum for
the instrument itself. The second word of the measurement is the size in
GLints of the entire measurement so that any parser can step over
measurements with which it is unfamiliar. Currently there are no
implementation independent instruments to describe. Some implementation
dependent instruments are described in the Machine Dependencies section
of this page.
In a single measurement, if multiple instruments are enabled, the data
for those instruments can appear in the buffer in any order.
If no instruments are enabled executing ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX,
ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, or ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssss will not write measurements
to the buffer.
The number of measurements taken since the buffer was reset can be
queried with ggggllllGGGGeeeetttt using GGGGLLLL____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT____MMMMEEEEAAAASSSSUUUURRRREEEEMMMMEEEENNNNTTTTSSSS____SSSSGGGGIIIIXXXX.
To determine whether a measurement has been written to the buffer call
ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. If a new measurement has appeared in the buffer
since the last call to ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, 1 is returned, and the
value of marker associated with the measurement by ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
or ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is written into the variable referenced by
_m_a_r_k_e_r__p. The measurements will appear in the buffer in the order in
which they were requested. If the buffer overflows, ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
may return -1 as soon as the overflow is detected, even if the
measurement being polled did not cause the overflow. (An implementation
may also choose to delay reporting the overflow until the measurement
that caused the overflow is the one being polled.) If no new measurement
has been written to the buffer, and overflow has not occurred,
To get a count of the number of new valid GLints written to the buffer,
call ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. The value returned is the number of GLints
that have been written to the buffer since the last call to
ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. If the buffer has
overflowed since the last call to ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, -1 is returned
for the count. Note that ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX can be used independently
of ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX.
ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX and ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX are
part of the GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss extension, not part of the core GL
command set. See ggggllllIIIInnnnttttrrrroooo for information about using extensions.
EEEERRRRRRRROOOORRRRSSSS
If _s_i_z_e is negative, GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated.
GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is executed
twice without an intervening execution of ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or
ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. Symmetrically, GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated
if ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is executed twice without an intervening
ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX will generate
GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN if executed after an execution of ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssss
without an intervening execution of ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or
ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. Executing any of ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX,
ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, or ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssss without a successful
execution of ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX to define a buffer will generate
GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if any of ggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX,
ggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is executed between the
execution of ggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of ggggllllEEEEnnnndddd.
ggggllllGGGGeeeetttt with argument GGGGLLLL____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT____MMMMEEEEAAAASSSSUUUURRRREEEEMMMMEEEENNNNTTTTSSSS____SSSSGGGGIIIIXXXX
ggggllllGGGGeeeettttPPPPooooiiiinnnntttteeeerrrrvvvv with argument GGGGLLLL____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT____BBBBUUUUFFFFFFFFEEEERRRR____PPPPOOOOIIIINNNNTTTTEEEERRRR____SSSSGGGGIIIIXXXX
ggggllllGGGGeeeettttSSSSttttrrrriiiinnnngggg with argument GGGGLLLL____EEEEXXXXTTTTEEEENNNNSSSSIIIIOOOONNNNSSSS
The SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss extension is supported only on IIIInnnnffffiiiinnnniiiitttteeeeRRRReeeeaaaalllliiiittttyyyy
systems.
The GGGGLLLL____IIIIRRRR____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT1111____SSSSGGGGIIIIXXXX instrument is implemented only on
IIIInnnnffffiiiinnnniiiitttteeeeRRRReeeeaaaalllliiiittttyyyy systems. Each measurement uses 10 words of the buffer.
The first (index 0) will be GGGGLLLL____IIIIRRRR____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT1111____SSSSGGGGIIIIXXXX itself. The second
word (index 1) will be 10. The following words are:
COUNTEMPTY (index 2) Increments each clock cycle for which a word of
screen-space geometry, pixel, or texel data was not transferred from
the GE board to the RM board. A high value could indicate that
rendering is geometry-limited or host-limited (because the GE is not
delivering commands to the RM as fast as the RM can process them),
or that rendering is rasterization-limited (because the RM is
working on previous commands and is refusing to accept new data from
the GE). Unfortunately there is no simple way to distinguish
between these two cases. The counter is set to zero by
ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, and by ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX after its value
has been written to the buffer.
COUNTDRAW (index 3) Increments each clock cycle for which a word of
screen-space geometry or pixel data (but not texel data) is
transferred from the GE board to the RM board. The counter is set
to zero by ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, and by ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
after its value has been written to the buffer.
COUNTLOAD (index 4) Increments each clock cycle for which a word of
texture data is written to the texture memory. The counter is set
to zero by ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, and by ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
after its value has been written to the buffer.
MAILBOX_TIMESTAMP (index 5) Contains the value of COUNTALL (see
below) at the time ggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
was called.
COUNTALL (index 6) Increments every clock cycle. No effort is made
to prevent wrapping.
PAD (index 7) Unused.
MARKER (index 8) Holds the value of the marker passed to
ggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX for this measurement.
MAILBOX (index 9) Holds a value that is used by the implementation.
Typically a sequence identifier, set after the buffer has been
specified, starting at 1 with the first measurement and incrementing
